提案|主体_以贡献飞桨框架API为例，手把手教你从User进阶到Contributor

篇首语：本文由编程笔记#小编为大家整理，主要介绍了以贡献飞桨框架API为例，手把手教你从User进阶到Contributor相关的知识，希望对你有一定的参考价值。

2016年9月&＃xff0c;飞桨框架正式开源。飞桨框架建设并非只靠百度工程师&＃xff0c;也离不开热爱飞桨、热爱开源的开发者们&＃xff0c;他们用自己的方式参与飞桨框架建设&＃xff0c;与飞桨共同成长。作为大型开源项目&＃xff0c;飞桨社区十分欢迎各位开发者积极提出需求或不足&＃xff0c;并主动提交pr解决。本文将由开发者李其睿介绍贡献API的经验。

前段时间百度飞桨组织了飞桨黑客马拉松第三期活动&＃xff0c;该活动发布了诸多有趣的开发任务。我参与了基础API方向的开发任务&＃xff0c;并新增了paddle.triu_indices API。这个API可以获取一个Tensor主对角线所有右上方元素的坐标&＃xff0c;在不久前发布的飞桨2.4版本中已经上线(官方文档)。借此机会记录一下开发过程&＃xff0c;供有兴趣为飞桨贡献的小伙伴入门参考。

感兴趣的同学可以直接参考PR:

• 飞桨代码

  https://github.com/PaddlePaddle/Paddle/pull/45168

• 文档

  https://github.com/PaddlePaddle/docs/pull/5161

• 提案

  https://github.com/PaddlePaddle/community/pull/207

一个API背后的组成

由于飞桨核心是由C&＃43;&＃43;构建的&＃xff0c;通过Python封装了API供用户使用&＃xff0c;因此每个API均对应着Python部分的代码和C&＃43;&＃43;部分的代码&＃xff0c;以下将分开介绍。

C&＃43;&＃43;部分

现在飞桨的算子库核心代码都在paddle/phi这个目录下。

• paddle/phi/kernels: 这个目录下是算子的实现部分&＃xff0c;分别需要实现“.h”文件&＃xff08;头文件&＃xff09;、 “.cc”文件&＃xff08;CPU算子&＃xff09;、“.cu”文件&＃xff08;GPU算子) 这三个部分&＃xff1b;

• paddle/phi/infermeta: 这个目录下的文件是推理一个API的输出参数的meta数据&＃xff0c;例如&＃xff1a;数据维度、数据type等。该目录下有多个文件&＃xff0c;根据算子输入Tensor的参数数量确定InferMeta函数放置位置&＃xff0c;比如算子输入Tensor参数是0个&＃xff0c;那推理函数需要放在nullary.cc/h中&＃xff1b;如果是Tensor参数有2个&＃xff0c;则需要放在binary.cc/h中&＃xff1b;

• paddle/phi/api/yaml&＃xff1a;这个目录下是用以注册API属性的yaml文件&＃xff0c;需要在yaml文件中添加你新增API的一些属性信息。

Python部分

Python部分相对而言内容比较少了&＃xff0c;主要在python/paddle目录下。

• python/paddle/tensor/creation.py: 这个文件主要是用来构造该API在Python端调用时的接口&＃xff0c;其中包含了入参的校验、算子的调用过程。另外英文版的API文档也在这里进行编写&＃xff1b;

• python/paddle/_init_.py&＃xff1a;初始化文件&＃xff1b;

• python/paddle/fluid/tests/unittests/test_xxxx.py&＃xff1a;单测文件。

文档

一个API的完整构建&＃xff0c;除了代码的开发外&＃xff0c;其文档的撰写也是非常必要的。飞桨的中文文档位于PaddlePaddle/docs仓库中。

• docs/api/paddle/Overview_cn.rst中用一句话对API的功能进行简要概述&＃xff1b;

• docs/api/paddle/xxxxx_cn.rst对于新增的API&＃xff0c;需要新增一个rst文件进行文档撰写&＃xff0c;撰写内容包括API的输入、输出、代码示例等。

撰写提案

当着手开发一个新的API时&＃xff0c;第一步不是写代码&＃xff0c;而是进行分析和设计。

关于设计&＃xff0c;有以下几点需要注意&＃xff1a;

• 飞桨的现状。想要实现的API是否不存在、是否可以由其他API组合方式实现&＃xff1f;

• 业内是否有此API&＃xff1f;例如PyTorch、NumPy、TensorFlow等&＃xff0c;如果有的话他们是怎么实现的&＃xff1f;哪种实现方式更好&＃xff1f;

• 飞桨中新增的这个API的命名、参数设计。

• 测试方案设计。

作为社区开发者&＃xff0c;我们可以综合上述几点将设计写成文档&＃xff0c;提交至Coummunity库&＃xff0c;与飞桨的工程师沟通、调整并确定方案。

正式开发

拉代码并成功编译

• 首先在Paddle仓库的GitHub页面上fork一份代码&＃xff1b;

• 最方便的搭建开发环境的办法就是使用飞桨官方提供的Docker镜像&＃xff1b; 

• 然后在Docker镜像内clone&＃xff0c;并切换到develop分支(最好在做每个任务时从develop分支checkout一个新分支&＃xff0c;会更方便)。

顺利的话到此就编译成功。编译好的whl文件在 /paddle/build/python/dist目录下&＃xff0c;进入目录使用pip install安装。

以后修改完代码就重复执行make、pip3 install的过程即可。

到此就可以正式开始写代码

第一步&＃xff1a;首先需要实现最核心的kernel部分。

让我们从最简单的部分开始&＃xff0c;头文件triu_indices_kernel.h。头文件通常不需要写主要的代码逻辑&＃xff0c;只要注册好方法就好。

第二步&＃xff1a;接下来需要实现CPU端的代码逻辑triu_indices_kernel.cc。

CPU端的主体的计算逻辑其实并不复杂&＃xff0c;这里对代码的几个注意点进行说明&＃xff1a;

• kernel需要在phi这个命名空间下&＃xff1b;

• 受Python书写习惯影响&＃xff0c;有时会输出return。更好的方式是将输出需要用到的内存分配后作为参数传入kernel&＃xff1b;

• 需要多关注边界条件&＃xff0c;以及不要受惯性思维限制。比如Tensor不一定是正方形&＃xff0c;对角线也不一定是主对角线&＃xff0c;对于这类非常规情况的处理需要格外注意&＃xff0c;这些情况可能也是需要代码量最多的地方&＃xff08;如下图所示&＃xff09;&＃xff1b;

• 最后通过PD_REGISTER_KERNEL注册算子。 

第三步&＃xff1a;接下来需要实现GPU端的kernel&＃xff1a;triu_indices_kernel.cu。

编写GPU kernel需要有一点CUDA的基础知识&＃xff0c;这里需要稍加学习&＃xff0c;理解基础的概念。如果零基础的话&＃xff0c;指路比较好的入门资料如下&＃xff1a;

• 一个入门博客&＃xff1a;

https://face2ai.com/program-blog/#GPU编程&＃xff08;CUDA&＃xff09;&＃xff1b;

• 两本入门书&＃xff1a;《CUDA By Example》《Professional CUDA C Programming》

在编写GPU kernel时&＃xff0c;我们需要抛弃掉往常写代码线性执行代码的思想&＃xff0c;将整个计算任务展开成一个计算组。有许许多多个worker帮我们&＃xff0c;每个worker只需要负责很小一部分数据计算即可。当转变成并行计算的思想后&＃xff0c;代码编写和理解就会稍微简单一些。

由于整体的kernel代码较长&＃xff0c;这里不再另作展示&＃xff0c;有需求的可自行前往代码库里查看。

第四步&＃xff1a;写完两个kernel&＃xff0c;最难的部分就结束了&＃xff0c;下面该写配套代码了。

首先是推理meta信息所在&＃xff1a;nullary.cc和nullary.h。这一步很简单&＃xff0c;在nullary.h里进行函数声明&＃xff0c;在nullary.cc里实现具体推理meta信息的逻辑。.cc文件内较为复杂的是需要计算输出的shape&＃xff0c;当输入是正方形&＃xff0c;对角线就是主对角线&＃xff0c;其计算很简单。但当输入是矩形&＃xff0c;对角线进行了向上或向下平移的话则需要考虑不同的情况。

第五步&＃xff1a;最后一项工作就是注册算子。在legacy_api.yaml中添加信息&＃xff08;最新develop已经更新为legacy_op.yaml&＃xff09;。

根据格式规范&＃xff0c;写清楚API的名字、参数等重要信息。

第六步&＃xff1a;下面就是轻松的Python代码环节。首先说核心的creation.py。

这里定义的函数格式就是以后使用该API过程中交互的格式。

def triu_indices(row, col&＃61;None, offset&＃61;0, dtype&＃61;&＃39;int64&＃39;):
    """
    英文文档部分
"""
# 校验各入参类型
# 根据计算图类型引用算子
# 返回计算结果
        )
    return out

其中主要做的是例如参数校验、与op交互等过程。另外&＃xff0c;这里的文档编写是直接展示在英文版飞桨文档网页的&＃xff0c;需要认真编写。编写完成后&＃xff0c;在__init__.py中导入即可。

到这里API主体代码就全部完成了&＃xff0c;可以执行make、pip install去进行测试了。这里可以先试验&＃xff0c;体验一下自己的工作成果。

import paddle
data1 &＃61; paddle.triu_indices(4,4,0)
print(data1)
Tensor(shape&＃61;[2, 10], dtype&＃61;int64, place&＃61;Place(cpu), stop_gradient&＃61;True,
Output:
       [[0, 0, 0, 0, 1, 1, 1, 2, 2, 3],
        [0, 1, 2, 3, 1, 2, 3, 2, 3, 3]])

单测的编写

简单的体验看起来是没问题的&＃xff0c;下面需要编写详尽的单测案例来进行测试。主要测试以下几项&＃xff1a;

• 函数功能在各种参数配置下是否都正确&＃xff0c;可以与NumPy、PyTorch进行比较&＃xff1b;

• 函数在动态图、静态图中是否都可以正常使用&＃xff1b;

• 函数是否能正常报错。

当所有的单测都通过&＃xff0c;API的代码开发就基本完成了。只剩最后一项&＃xff0c;编写中文文档。

文档编写

文档主要内容包括API的功能、接口形式、入参/出参的具体含义和格式以及使用示例。这几部分内容和英文文档几乎可以一一对应&＃xff0c;写完一个可再翻译另一个。

到此&＃xff0c;整个API开发的流程就结束了。通常在开发编译时会反复报错、debug、修改代码、重试&＃xff0c;这些过程是必不可少的&＃xff0c;最终体验到的喜悦也是难以言表的。

如果你也想加入开源、体验贡献开源的乐趣&＃xff0c;快来参加&＃x1f447;

飞桨快乐开源活动&＃xff1a;快来提PR&＃xff0c;领取新年礼物啦

为鼓励更多的开发者参与到飞桨社区的开源建设中&＃xff0c;帮助社区修复bug或贡献feature&＃xff0c;加入开源、共建飞桨。飞桨快乐开源活动暖冬来袭&＃xff0c;我们提供了三种类型的贡献任务&＃xff0c;并为完成任务的贡献者准备了礼品表示感谢&＃xff01;

如果你对提PR仍有问题&＃xff0c;欢迎在评论区留言或扫描下方图片二维码沟通咨询~

关注【飞桨PaddlePaddle】公众号

获取更多技术内容~